Skip to content

feat: drive sessions from the bridge's web page, every command signed by the browser's own key - #198

Merged
deymosh merged 6 commits into
masterfrom
docs/web-client-design
Nov 17, 2026
Merged

deymosh merged 6 commits into
masterfrom
docs/web-client-design

Conversation

@deymosh

@deymosh deymosh commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Summary

The bridge's web page becomes a client: a browser drives the bridge's sessions as the phone does. Its commands are signed by a key of its own that its page cannot hand out. This PR started as the design (docs only). At the maintainer's request it now carries the whole feature, one commit per layer:

  1. protocol — protocol::web: the browser's stream (CHALLENGE / HELLO / READY / CLOSED / CMD / OK / MSG / PAGE / REPLY). The signed input binds the machine, the browser, the connection's challenge, a growing seq and the exact body text. BrowserKey reads WebCrypto's raw P-256 point and verifies its r‖s signatures with RustCrypto p256 (pure Rust, new dependency). A WebCrypto-made test vector proves the bridge reads what a browser writes. The corpus gains webFrames, and the totality properties run the new decoder.
  2. bridge-core — a browser is a client of the identity that let it in (Addressee::browser). It gets copies like a phone's client: live text only for the session on screen, replies to itself alone. browser_may_send names every command. A browser drives sessions and reads; keys, other browsers' sign-ins, secrets, terminals, uploads and agent-configuration writes stay with the phone. Unpairing an identity ends its browsers.
  3. bridge-runtime: the stream — the key arrives with POST /api/sign-in, bound before the phone sees the code. /api/stream is gated by Host, Origin and cookie, then every frame must verify with a growing seq. A cookie alone reaches only /api/me, the QR and its own sign-out. The status, browsers, devices and config routes are gone: those now come through the stream. 7 idle days (only a signature moves lastSeenMs) or 30 days in all end a browser. A browser that stops reading is closed, never waited on.
  4. bridge-runtime: the page — a Sessions tab with the session list, the transcript (text built as elements, never HTML), live text, permission/question/plan cards, input, Stop, End, the mode picker and new sessions. Plus tests/web_page.rs, an end-to-end test with a real runtime, agent host and paired phone core, run with the other e2e runs (codedeck e2e, CI).
  5. android — before a code goes out, "Check the page" shows the certificate fingerprint the heartbeat pins, laid out as browsers' certificate viewers show it. Only "They match: sign in" sends it. The machine summary gains directCertSha256.
  6. docs — docs/WEB-CLIENT.md: the design, the threat model, the stream, the allowlist, the lifetimes, rendering, cost and tests. BRIDGE, PROTOCOL, CLIENT and the README are brought in line. CLAUDE.md changes too: the signing rule now names the browser as the one other signer, and the e2e runs include the web page's.

Decisions made beyond the agreed outline:

  • The key is bound at sign-in start, so web-sign-in is unchanged on the wire.
  • The browser's id is the SHA-256 of its public key.
  • There is no automatic resend of a command whose OK was lost.
  • The page renders the wire itself in plain JS, about 60 KB. client-core in wasm would need nostr feature-gated out of protocol, a wasm build in every release, and 'wasm-unsafe-eval' in the CSP. WEB-CLIENT.md gives the reasoning.

Data change (no migration): web-sessions.json records from before browser keys have no key and are skipped on load, so already signed-in browsers sign in again. web-browsers' id now comes from the key, and expiresMs is when the browser actually lapses.

What review changed (folded into the commits)

  • CI (Windows): the end-to-end test created its session before the agent host had reported its catalog. The bridge rightly answers that with session-failed, so the test now waits for the catalog and fails at once on a refusal.
  • Bug hunt, all checked against the code and fixed:
    • The page signed overlapping frames concurrently, so a reconnect's presence and sync could go out of seq order. The bridge closes that as bad-signature and the browser would have been signed out. Frames are now signed and sent one at a time.
    • Page requests and the stream gate now check the approving identity is still paired, covering a record restored from disk after an unpair.
    • A browser dropped to make room, or reaped as lapsed, now loses its open streams.
    • An open stream no longer holds its host's direct-link slot (8 per address, per /64 on IPv6), so tabs cannot lock a phone out.
    • Page fixes: a new session stuck at "Starting…" after a drop, sync acks sent under a newer sync's id, and a malformed #sessions/… hash breaking every render.

Traffic cost

No new relay traffic and nothing for phones. A browser's copies are neither encrypted nor signed, live text goes only to its session on screen, and an open tab renews its presence every 5 minutes. The phones' links never wait on a browser.

Verification

  • ./codedeck check green (host typecheck/test/build; clippy, test, doc with -D warnings), ./codedeck e2e green (now including web_page), and ./codedeck android test verifyPaparazziDebug lintDebug: 204 tests, lint "No issues found". I looked at each changed golden.
  • New tests were proven against broken code: removing the engine's allowlist check, or the stream's seq check, makes them fail.
  • The design's gate was checked live: crypto.subtle with a non-extractable key works over a LAN address in Chrome (the warning bypassed by flag), and the key survives a reload through IndexedDB.
  • The real page was driven in headless Chrome against a bridge with a paired phone core (the test's hold tool): sign-in, a new session, input and its echo, a permission card answered, a reload that syncs the transcript, every tab, phone width. There were no script or CSP errors; the only 404 was /favicon.ico.
  • Not checked: Firefox and Safari, and the phone's new step on a device.

🤖 Generated with Claude Code

deymosh and others added 2 commits November 17, 2026 23:46
The bridge's web page is going to drive sessions, which means running
commands on the machine, so a browser's commands must carry more than a
bearer cookie. protocol::web is the spec for its stream: JSON arrays over
one WebSocket (CHALLENGE, HELLO, READY/CLOSED, CMD/OK, MSG, PAGE/REPLY),
every browser frame signed by a WebCrypto ECDSA P-256 key of the browser's
own over the machine, the browser id, the connection's challenge, the seq
and the body exactly as sent.

BrowserKey reads the raw uncompressed point the page exports (refusing one
off the curve), derives the browser's public id from its SHA-256, and
verifies WebCrypto's r||s signatures with RustCrypto's p256 (pure Rust).
A test vector made by WebCrypto proves the bridge reads what a browser
writes. The decoder is total: the corpus gains webFrames, and the
totality properties run the new decoder and key parser.

Co-Authored-By: Claude Code <[email protected]>
A browser that a paired phone let in is now a principal of the engine:
a client of the identity that approved it, addressed as
Addressee::browser(identity, id), whose copies the runtime writes to the
browser's stream instead of encrypting them. Copies to an identity reach
its browsers with a stream open, live text only those watching that
session (presence works as for a phone's client, with the same catch-up),
never a terminal's output; a reply goes to the asking browser alone.

browser_may_send names every command: a browser drives sessions and reads,
and never sends what belongs to an identity (session-key, pair-request,
web-sign-in: no browser lets in another), what moves a secret or a
sign-in, a terminal command (the allowlist names devices), an upload or an
agent-configuration write. The engine ignores the rest, and a command from
a browser whose identity is no longer paired. Unpairing an identity ends
the browsers it let in (Effect::WebEndBrowsers, which the runtime's page
carries out).

dispatch now takes the terminal's TerminalVia rather than the relay Via,
the only thing it used it for.

Co-Authored-By: Claude Code <[email protected]>
@deymosh
deymosh force-pushed the docs/web-client-design branch from e831800 to 8791311 Compare November 17, 2026 22:55
@deymosh deymosh changed the title docs: design the web page as a full client feat: drive sessions from the bridge's web page, every command signed by the browser's own key Nov 17, 2026
deymosh and others added 4 commits November 18, 2026 00:05
A browser now signs in with a key: POST /api/sign-in carries the public
half of a WebCrypto P-256 key, bound to the pending sign-in before any
phone sees its code. Its id is the key's (protocol::web), and the key is
kept in web-sessions.json beside the cookie's hash.

GET /api/stream (a WebSocket on the page's path; every other upgrade is
still a phone's direct link) is let through only for an allowed Host, the
page's own Origin and a signed-in cookie. The browser then signs the
connection's challenge and every frame after it, each with a growing seq;
a frame that does not verify, or replays a seq, closes the stream. A
verified command is checked against bridge_core::browser_may_send and
handed to the engine as Input::WebCommand; the first and last stream of a
browser make it a present client of its identity or not. What the engine
sends a browser goes down its stream through the direct link's lane: never
waited on, and a browser that stops reading is closed as busy.

The cookie alone now reaches only /api/me (which also tells the page its
machine and id), the QR and its own sign-out. The status, browsers,
devices and config routes are gone: the heartbeat arrives on the stream,
the browser list through the phone's own web-browsers commands, and
devices/config as signed page requests.

A browser signed in for 30 days also lapses after 7 days without signing
anything. Only a signature moves lastSeenMs, so a copied cookie cannot keep
it alive; web-browsers' expiresMs is when it actually lapses. A lapse,
sign-out, revocation or unpairing closes its streams with the reason.

Data: a web-sessions.json record from before browser keys has none, and
is skipped on load; those browsers sign in again.

Co-Authored-By: Claude Code <[email protected]>
The page becomes a client. At sign-in it makes a WebCrypto ECDSA P-256 key
whose private half cannot be exported, keeps it in IndexedDB and sends the
public half with the start; once the phone has let it in (and the key it
holds is the one /api/me names), it opens the signed stream and signs
every frame with it.

A Sessions tab, first: the sessions beside the one open, its transcript
(text, light markdown built as elements, thinking, tool calls with their
input, result and diff, plans, to-dos, background tasks, notices), live
text for the session on screen only, permission, question and plan cards
answered in place, input (Enter sends), Stop, End, the mode picker and a
new session on any agent and folder. A transcript is synced like the
phone's (sync-request with the ranges held, acks batched) and survives a
reload. Presence says which session is on screen and renews every five
minutes, which also keeps an open tab's sign-in from idling out. Every
string from the bridge is set as text: a transcript holds whatever a tool
read. The Browsers, Devices and Settings tabs read through the stream.

tests/web_page.rs drives the real runtime and agent host with a paired
phone core and a browser played over pinned TLS: the key at sign-in, the
phone's approval, a session created and answered over the stream, the
phone seeing it, and the phone's sign-out closing the stream. It runs
with the other end-to-end tests (codedeck e2e, CI). Its second test is a
tool that holds such a bridge for a real browser; the page was driven
through it in headless Chrome (sign-in, a session, input, a permission
card, a reload, every tab, phone width) with no script or CSP error.

Co-Authored-By: Claude Code <[email protected]>
A browser opening the bridge's web page meets a certificate warning, since
the certificate is the bridge's own; whoever sits between the browser and
the bridge can only be caught there. The phone already pins that
certificate from the bridge's signed heartbeat, so the Browsers page now
shows it before a code goes out: a scanned or typed code lands on "Check
the page", with the SHA-256 written as browsers' certificate viewers write
it (uppercase pairs, colon-separated, eight to a line) and the code, and
only "They match: sign in" sends it.

The machine summary carries the pin itself (directCertSha256) besides
directPinned. The lifetime the page states follows the bridge's: signed in
while used, ended by 7 idle days or 30 in all.

Co-Authored-By: Claude Code <[email protected]>
docs/WEB-CLIENT.md is the design of the web page as a client: why the
browser speaks the protocol's own JSON over TLS rather than Nostr, the
threat model, the sign-in with a key of the browser's own bound before the
phone approves, the stream and its signed input, what a browser may send,
the lifetimes (7 idle days, 30 in all), why the page renders the wire
itself rather than client-core in wasm, the cost, and the tests (with the
tool that holds a bridge for a real browser).

BRIDGE.md's web page section describes the page as it is now (sessions
driven from the browser, the HTTPS routes a cookie still reaches, the stream
caps); PROTOCOL.md gains the browser's stream and the new meaning of a
browser's id and expiresMs; CLIENT.md the phone's certificate check; the
README its line. CLAUDE.md: the signing rule names the browser as the one
other signer, and the e2e runs include the web page's.

Co-Authored-By: Claude Code <[email protected]>
@deymosh
deymosh force-pushed the docs/web-client-design branch from 8791311 to ed5538d Compare November 17, 2026 23:08
@deymosh
deymosh merged commit 2aa4578 into master Nov 17, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant